import { Callout } from 'nextra/components'

# Quickstart Guide

The easiest way to try out Plane is to use Docker Compose. These instructions are for a Linux or Mac environment
with Docker installed.

## Quickstart Steps

### 1. Clone Plane’s [git repo](https://github.com/jamsocket/plane)

```bash
git clone https://github.com/jamsocket/plane.git
cd plane
```

### 2. Start Plane

```bash
docker compose -f docker/docker-compose.yml up
```

This will run:
- An instance of Postgres
- A Plane controller
- A Plane “drone”
- A Plane proxy

See the [architecture overview](concepts/architecture.mdx) for background on each Plane component.

### 3. Connect to a backend

```bash
docker/cli.sh \
    connect \
    --cluster 'localhost:9090' \
    --key 'my-first-backend' \
    --image 'ghcr.io/jamsocket/demo-image-drop-four'
```

You can think of Plane as a big key-value store that associates “keys” (arbitrary strings) with running processes
([session backends](concepts/session-backends.mdx)).

When you issue a “connect” request, Plane will return a URL that routes to the process associated with the key you provide.
If no process is running, Plane will start one (provided that you supply an image name in the connect request).

Here’s a breakdown of the command above:

- `docker/cli.sh` is a shell script that runs the Plane CLI in a Docker container, pre-configuring it to point to
  a Plane instance started in the Docker Compose file.
- `connect` is the Plane CLI subcommand for issuing a “connect request”, which will return a URL that routes to
  a backend process.
- `--cluster 'localhost:9090'` tells the CLI to start the backend on the `localhost:9090` cluster. Since the cluster name
  includes a port (`:9090`), Plane will treat it as a “development” cluster and not enable HTTPS on it. See [clusters](concepts/clusters.mdx)
  for more details.
- `--key 'my-first-backend'` tells the CLI to associate the backend with the key `my-first-backend`. The first time we run
  this command, no backend with the key `my-first-backend` will exist, so Plane will start a new backend process. If we
  subsequently run this command again while that backend process is still running, Plane will return a URL that routes
  to that backend process.
- `--image '...'` tells the CLI that if it needs to start a new backend process,
  it should use the given Docker image. In this case, the image serves a simple turn-based multiplayer game.

<Callout type="info">
  At least one of `--key` or `--image` must be provided, but it is not necessary to include both.

  If you **only** want to connect to an existing backend, you can provide `--key` only. If a
  backend with the given key is not running, Plane will return an error.

  If you **don’t** want to connect to an existing backend process, you can provide `--image` only.
  Plane will use a unique key to start a new backend, and return a URL that routes to it.
</Callout>

When you run the command above, you should see output like this:

```
Created backend: ba-xt8nmtlgti18qx
URL: http://localhost:9090/tYVHfS4PKgufdhwGCnn6LLfAaCo_iAHitbw4Bg8ETjA/
Status URL: http://0.0.0.0:8080/pub/c/localhost:9090/b/ba-xt8nmtlgti18qx/status
```

The first line tells you that Plane has created a backend with the key `ba-xt8nmtlgti18qx`. The second line tells you
a URL that routes to that backend. The third line tells you a URL that you can use to check the status of the backend
as JSON.

Below that output, it will show a running list of states and the time they were entered. The first
time you run a particular image, it may spend some time in the `loading` state, because it will download the container
image if it does not have it cached.

Once the image is in the `ready` state, you can open the URL provided in your browser to open the game.

## Docker Compose Configuration

The Docker Compose file defines four services:

| Container        | Image                | Port |
|------------------|----------------------|------|
| plane-postgres   | `postgres:16`        | 5432 |
| plane-controller | `plane/plane:latest` | 8080 |
| plane-drone      | `plane/plane:latest` |      |
| plane-proxy      | `plane/plane:latest` | 9090 |

Note that the name of the cluster (`localhost:9090`) refers to the port of the proxy, not the controller.
This is because the name of the cluster refers to the address that end-user clients will use to access the
backends, and clients access backends through the cluster. See [the documentation on clusters](concepts/clusters.mdx)
for more information.
